.\"
.\" Copyright (c) 2007 Mikolaj Golub
.\"	All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id: bsnmp-ucd.8 115 2013-10-11 17:55:28Z to.my.trociny $
.\"
.Dd October 11, 2013
.Dt bsnmp-ucd 8
.Os bsnmp-ucd
.Sh NAME
.Nm bsnmp-ucd
.Nd an SNMP module which implements parts of UCD-SNMP-MIB.
.Sh DESCRIPTION
.Nm
is a module for 
.Xr bsnmpd 1
which allows to get memory, load average, cpu usage and other system
statistics. It implements parts of UCD-SNMP-MIB for this.
.Pp
.Sh OPTIONS
To activate the
.Nm
module add this string to
.Pa /etc/snmpd.config:
.Bd -literal -offset indent
begemotSnmpdModulePath."ucd" = "/usr/local/lib/snmp_ucd.so"
.Ed
.Pp
.Sh MIBS
The counters will be available under the following MIB:
.Bd -literal -offset indent
 .1.3.6.1.4.1.2021
.Ed
.Pp 
Or if the appropriate MIB file has been installed:
.Bd -literal -offset indent
UCD-SNMP-MIB::ucdavis
.Ed
.Pp
With
.Nm
you can also extend bsnmpd agent functionality specifying arbitrary
commands in UCD-SNMP-MIB::extTable. To add new command you should add
following lines in
.Xr bsnmpd 1
configuration file, in
.Nm
module section:
.Bd -literal -offset indent
extNames.<INDEX> = <name>
extCommand.<INDEX> = <commandline>
.Ed
.Pp
For example, to collect lastpid statistics under mib
UCD-SNMP-MIB::extOutput.0 you can specify:
.Bd -literal -offset indent
extNames.0 = "lastpid"
extCommand.0 = "/sbin/sysctl -n kern.lastpid"
.Ed
.Pp
Note: Index order is important. Commands should be indexed beginning
from 0 and without gaps.
.Pp
When program has finished, the exit status is available via extResult mib
and the first line of output is placed in extOutupt mib. The next time
the program will be run only after some period of time (this period is
set in sources and can be changed only by recompiling module).
.Pp
It is possible to specify command that will be run to fix
problem when extension command returns nonzero status. For this,
together with previous two mibs for extension command, the following
mibs should be set:
.Bd -literal -offset indent
extErrFix.<INDEX> = 1
extErrFixCmd.<INDEX> = <fix command>
.Ed
.Pp
For example, to monitor apache and restart process when it is down,
you can add to configuration file:
.Bd -literal -offset indent
extNames.1 = "apache"
extCommand.1 = "/usr/local/etc/rc.d/apache status"
extErrFix.1 = 1
extErrFixCmd.1 = "/usr/local/etc/rc.d/apache restart"
.Ed
.Pp
Also, it is possible to monitor processes using prTable. For example:
.Bd -literal -offset indent
prNames.0 = "httpd"
prMin.0 = 3
prMax.0 = 100

prErrFix.0 = 1
prErrFixCmd.0 = "/usr/local/etc/rc.d/apache22 restart"
.Ed
.Pp
There several parameters that can be used to tune
.Nm
module behaviour:
.Bl -tag -width ".Ic extUpdateInterval"
.It Ic updateInterval
Statistics update interval, in ticks.
The default is 500 ticks (5 seconds).
.It Ic extCheckInterval
External commands check interval, in ticks.
The default is 100 ticks (1 second).
.It Ic extUpdateInterval
External commands update interval (used e.g. by fix commands executor),
in ticks.
The default is 3000 ticks (30 secondd).
.It Ic extTimeout
External commands start timeout.
The default is 60 seconds.
.El
.Pp
The parameters can be changed either in
.Xr bsnmpd 1
configuration file, in
.Nm
module section, or at run time, setting the corresponding mibs under
UCD-SNMP-MIB::ucdavis.1.
.Sh SEE ALSO
.Xr bsnmpd 1 
.Sh AUTHOR
.An Mikolaj Golub
